Software Vault: The Gold Collection/Software Vault - The Gold Collection (American Databankers) (1993).ISO/cdr23/chansw53.zip/CHAINSAW.TXT

Text File | 1993-05-24 | 28KB | 715 lines

L---+---T1----+-T--2----T----3--T-+----4T---+---T5----+-T--R
.X:10
.XT:3
.XB:2
.H:
.H:
.H:
.F:
.F:
.F:
.F:























                          CHAINSAW

           A command line driven directory pruner

             Public Domain, 5/24/93, Ted Davis

                        Version 5.3

2
.X:10
.XT:3
.XB:2
.H:...CHAINSAW: overview
.H:
.H:
.F:
.F:
.F:
.F:...$$$...
CHAINSAW is a command line driven directory pruner.  It does
not stop for user confirmation and can, therefore, readily
be used from batch files.  It can generate comprehensive
reports of its actions.

       It provides optional password protection to prevent
casual prowlers from using it to accidentally (or
intentionally) trash a disk or directory.

       CHAINSAW is a cleaning tool, useful for a variety of
tasks from cleaning out the \temp directory of files,
subdirectories, or both, to completely wiping an entire disk
during reconfiguration for a new user.  This program is
potentially destructive (as is FORMAT) and is intentionally
somewhat difficult to use in its most destructive modes.  It
is intended mostly for technicians, system administrators,
and power users.  It is NOT intended for novice users, who
are advised to leave it strictly alone.

       The command line contains the complete path,
including drive, to the directory node at which the pruning
is to occur, a password (optional) and control switches
(also optional). Switches are provided to allow the program
to delete the files in the starting directory, and to remove
that directory, as well as all the subdirectories and their
contents, or just the subdirectories.  Other switches enable
operation on the root directory or network drives.  Another
group of switches control which of the program's messages
will be written and whether they go to STDOUT or STDERR.
Still other switches, used with a somewhat different syntax,
allow changing the password and default switches.


       CHAINSAW is FREEWARE, placed in the public domain
5/24/93 by the author, Ted Davis: it comes with absolutely
no warranty and the user's only recourse is refund of the
purchase price, which is nothing.  If you use this program,
you do so on your own responsibility.  If you don't want to
do that, erase your copy of the program RIGHT NOW.


       There is no formal support for the program, but you
do get the source code.  The author is not in a position to
provide support, but comments are welcome, as are
suggestions for improvements.  Since addresses and phone
numbers tend to change, but CompuServe ID numbers are
forever, I prefer to be contacted via CIS E-mail at
73500,2314 (but do not expect a quick reply).  If you find
this program useful, please let me know how you are using
it, what features you use (and never use), etc.  I know how
I use it and how my beta testers use it, but the program has
a lot more in it that we routinely use.
3
.H:...CHAINSAW: syntax, switches
.H:
.H:
SYNTAX (most cases):

CHAINSAW {drive:path} {password} [switches] <Enter>

SYNTAX for changing default switches or password:

CHAINSAW {switch and new data} {password} <Enter>

(No matter what, the password must be the second item in the
command tail, unless suppressed.)

The default password can be found elsewhere in this manual.

The program responds to Ctrl + C and Ctrl + Break by
aborting with an ERRORLEVEL of 3 and a warning that some
damage may have been done to the given directory branch.

------------------------------------------------------------

.H:...CHAINSAW: switches
.H:
.H:
SWITCHES, general:
Switches are introduced by a '/' or '-' character and
everything in the tail following the marker (except as noted
above) is considered a switch character or delimiter.  The
acceptable delimiters are '/', '-', ',', ';',  space, and tab.
Incorrect or stray characters in the command tail cause the
program to bomb with an "if you don't know what you are
doing, don't do it" message.

       In the following sections, the default switches are
marked with an '*'.

       Switches are processed in the order encountered,
defaults first, then those from the command tail, which can,
therefore, override the defaults.


SWITCHES, permission:
These enable or disable operations and locations.

f      Enables deletion of files in the starting directory.
       It is used to completely clean out a directory rather
       than just empty and remove its subdirectories.

F  *   Disables deletion of files in the starting directory.
       It is used to empty and remove the subdirectories of
       the starting directory while leaving the files in
       that directory intact.

g      Enables removal of the starting directory as well as
       all its contents, files as well as subdirectories.

G  *   Disables removal of the starting directory; only its
       subdirectories, and, optionally, files will be
       deleted.

4
n      Enables operations on network drives.

N  *   Disables operations on network drives.

p      Enables deletion of read-only, hidden, and system
       files in all permitted directories.

P  *   Disables deletion of read-only, hidden, and system
       files in all directories.

r      Enables operations in, but not on, the root
       directory, if it is the starting path.

R  *   Disables operations in the root directory.


SWITCHES, message control


?, h, or H
       Invokes the help screen, which is a VERY brief
       syntax and partial switch reminder.  No password is
       needed with this switch.

b      All messages are written to STDOUT, which can be
       redirected to a file or device.

B  *   Directs messages to their default destinations:
       Fatal error messages to STDERR
       Non-fatal error messages to STDOUT
       Informational messages to STDOUT
       File and directory deletion messages are not printed.

d      Enables directory removal listing to STDERR.

D      Enables directory removal listing to STDOUT.

e      Directs all messages to STDERR (the screen), which
       cannot be redirected.

E      Same as B.

l      Enables listing of deleted files to STDERR.

L      Enables listing of deleted files to STDOUT.

m      Directs all fatal and non-fatal error messages to
       STDERR without affecting informational and deletion
       messages.

M      Directs error messages to their default destinations.

5
o      Directs all fatal and non-fatal error messages to
       STDOUT without affecting informational and deletion
       messages.

O      Same as M.

s  *   Enables printing of a summary at termination.

S      Disables printing of the summary.

w  *   Turns the message output routine on.  This is needed
       only if the default has been changed to W.

W      Turns the message output routine off.  It is used in
       batch files instead of sending all the messages to
       STDOUT and redirecting it to NUL.

x      Turns off file deletion failure messages.

X      Turns off directory removal failure messages.


SWITCHES, default changing:

For all of these, except 'A', the new data string follows
the switch character without any delimiter.  If a password
is needed, it must follow the switch string and be separated
from it by at least one space.  The switch and string should
be the first command tail argument, the password, the
second.  No more than one of these switches can be used at a
time; the program terminates after processing the first one,
without even looking to see if there are more (well, almost
like that, it will process 'a' or 'A' even if the first
switch is 'z' or 'Z').  Although the default changing syntax
given above is the preferred form, it is possible to include
these switches in a normal command tail, but it is a waste
of effort since all that happens is the default change; the
program will not change defaults AND prune the directory on
the same pass.  Note: these write to the executable file,
but they still work if you rename the working copy of the
program.

a      Change default switch settings.  The string that
       follows the 'a' must be a legal switch string, it may
       contain '/' or '-' characters, but must not contain
       delimiters, unless the string is quoted.  Anything
       that would cause the string to be passed as more than
       one argument will cause an error (bad password).

A      Resets the original default switches, the ones marked
       with '*' in the preceding sections.

6
z      Changes the password to the string following the 'z'.
       The next argument must be the existing password, if
       any.  This switch removes the password if the 'z' is
       followed immediately by a space.  Lower case 'z'
       clears the screen to remove the passwords from view.

.H:...CHAINSAW: switches, messages
.H:
.H:
Z      Exactly like 'z' except that upper case 'Z' does not
       clear the screen.


------------------------------------------------------------
.H:...CHAINSAW: messages
.H:
.H:

MESSAGES, general:
On invocation, the program displays a copyright message to
STDOUT (unless the default is changed or overridden).  On
exit it displays a summary, the number of files deleted and
of directories removed to STDOUT (unless...).  In between,
it may or may not display some other message or list.

       The messages texts are listed in alphabetical order
within categories.  Variable text is indicated by <type>.
The messages are not necessarily in exactly the same format
as they are on the screen since the screen is assumed to be
80 columns and this text file is 60 columns wide.

       Note that file and directory removal list messages
both begin with "... " and removal failure messages begin
with "*** ".  This allows easy separation and sorting of the
message stream with various utility programs.

       The rather large number of switches controlling
message destinations are to allow generation of report files
with user determined contents.  A typical case would send
the list of file deletions to redirected STDOUT, suppress
directory deletion listing, and send everything else to the
screen (STDERR); another would send the error messages to
the file, information messages to the screen and suppress
the deletion messages.  In some batch file applications, any
message would be useless and all display could be
suppressed.

7
MESSAGES, informational:

... Deleted file: <filespec>.

       Indicates that the named file was successfully
       deleted.  This message must be specifically enabled
       with the 'l' or 'L' switch.  It is invoked when the C
       function 'unlink' succeeds.

... Removed directory: <path>.

       Indicates that the named directory was successfully
       removed.  This message must be specifically enabled
       with the 'd' or 'D' switch.  It is invoked when the C
       function 'rmdir' succeeds.


CHAINSAW <version> deletes, without prompts, entire
branches of a directory tree.

Syntax: CHAINSAW {path to base directory} {password}
{switches} or CHAINSAW <modification switch> <password> (The
drive letter is required, trailing '\' is optional.
Switches may be in /bde, /b/d/e, /b /d /e, /b,/d,/e, -bde, -
b-d-e, -b -d -e, etc. format, so long as the first one
immediately follows a '/' or '-'.)
    There are too many switches to define all of them here,
but... /A restores default switches, /a changes them;
b,B,d,D,e,E,l,L,m,M,o,O,s,S, w,and W control the way the
program writes its messages (and what messages it writes).
For the rest of the listed switches, lower case enables and
upper case disables the feature: f,F - file deletion in the
base directory; g,G - base directory removal; n,N -
operation on network drives; p,P - deletion of read-only,
hidden and system files; r,R - operation on the root
directory; See CHAINSAW.DOC for details."

       The help screen is invoked by a '?', 'h', or 'H'
       switch.

CHAINSAW aborted by user!
Directory <base path> and its subdirectories are probably
damaged.
       Occurs when the user presses Ctrl + Break or
       Ctrl + C.

Chainsaw deleted <number or "no"> file<s> and removed
<number or "no"> directories.

       This is the summary message displayed at the end of
       the program.  Its presence is controlled by the 's'
       and 'S' switches.

8
CHAINSAW...New password installed.
       This is the success message from the 'z' and 'Z'
       switches.  It indicates that no errors occurred
       during the process of encrypting the new password and
       writing the result to CHAINSAW.EXE.

CHAINSAW Version <version> is FREEWARE, Copyright 1992, Ted
Davis.
       This is the copyright message displayed when the
       program is invoked.   The 'w' and 'W' switches
       control its presence.

New default switches installed.
       This is the success message from the 'a' switch.  It
       indicates that there were no errors during the
       process of writing the new switch string to
       CHAINSAW.EXE.  It does not mean that the switch
       string makes sense or will work.

Original default switches reinstalled.
       This is the success message from the 'A' switch and
       means that the original list of default switches has
       been written to CHAINSAW.EXE.


MESSAGES, error:
Let us hope that you see few or none of these (but you
will).  Some of these are followed by the appropriate DOS
error message which can be used to help determine the cause
of the error (maybe, if you have enough DOS interrupt
reference material and the message is meaningful).

*** Deletion of file: <filespec> failed.
       'unlink' failed to execute properly.  The reason is
       likely to be obscure, perhaps a DOS error, the
       drive is not erasable or the disk is write protected,
       or the file is locked by another program on the
       network.

*** Deletion of file: <filespec> failed.  Error: read-only,
hidden, or system.
       The file attributes included one or more of those
       requiring special permission from the user for
       deletion.  The 'p' switch enables their deletion and
       prevents this message, except on write protected or
       read-only drives.

*** ERROR: <message>.
       This follows another message and provides what the
       makers of DOS and of Turbo C++ think of as helpful
       explanations of a DOS interrupt function failure.
       These messages are often useless, misleading, and/or
       cryptic but may be helpful to DOS experts and power
       users.

9
*** Removal of directory: <path> failed.
       'rmdir' failed to execute properly.  The most likely
       reason is that the directory, or one of its
       subdirectories is not empty, perhaps due to hidden,
       read-only, or system files that were not erased
       because you did not use the 'p' switch or an erasure
       failure.


DOS 3.0 or later is required.
       This message is self explanatory; the only cure is to
       upgrade your version of DOS, which you probably
       should have done anyway when DOS 5.0 came out.

Memory allocation ERROR, CHAINSAW aborted.
       This means either that the directory tree has too
       many subdirectories on the branch in work or that a
       DOS memory allocation error occurred.  CHAINSAW
       creates (and allocates memory for) a new instance of
       the 'dirkiller' object for the base directory and for
       each level of subdirectories within it.  This message
       occurs when the 'new' operator fails.

Password incorrect of file read error... CHAINSAW aborted.
       The most usual causes are a typo in the password and
       omission of all or part of the command tail.  It can
       also occur if CHAINSAW.EXE becomes corrupted or
       cannot find itself.

Unable to change password.
       This means that there was an error writing the new
       password to CHAINSAW.EXE, or in finding the existing
       one in the file.  Make sure that CHAINSAW.EXE is not
       marked read-only, that the disk is not write
       protected, and if on a network, that you have write
       permission for the directory in which it resides.  If
       none of that helps, it will be necessary to start
       over with an unmodified copy of the program as
       distributed.

Unable to change switches.
       This means that there was an error writing the new
       switches to CHAINSAW.EXE, or in finding the existing
       ones in the file.  Make sure that CHAINSAW.EXE is not
       marked read-only, that the disk is not write
       protected, and if on a network, that you have write
       permission for the directory in which it resides.  If
       none of that helps, it will be necessary to start
       over with an unmodified copy of the program as
       distributed.

10
The calling syntax for CHAINSAW was incorrect...
If you do not FULLY understand the syntax and what the
program does you should not attempt to use it.  This program
DESTROYS ENTIRE BRANCHES OF THE DIRECTORY TREE.
If used incorrectly, it can do untold damage.
       This is the barf message: there was something on, or
       missing from, the command line that the parser did
       not like.  Its primary purpose is to discourage
       browsers while protecting your hard disk(s).  In
       practice, you will get it most often by forgetting
       to include the entire command tail when invoking the
       program: CHAINSAW <Enter> will get it for you.  The
       absolute minimum command tail contains the complete
       path, including drive, to the starting directory, and
       unless you have turned off the password feature, the
       password.

11
.H:...CHAINSAW: ERRORLEVELS, SAFETY
.H:
.H:

ERRORLEVELS:
CHAINSAW returns an exit code which can be read and acted
upon by a calling batch file with the IF ERRORLEVEL test.

       ERRORLEVEL == 0 - Normal termination: everything went
                         OK, no problems.
       ERRORLEVEL == 1 - aborted due to some internal error
                         or command tail syntax error.
       ERRORLEVEL == 2 - ran to completion, but failed to
                         delete one or more files or
                         directories.
       ERRORLEVEL == 3 - user aborted with Ctrl + Break or
                         Ctrl + C.
       ERRORLEVEL == 4 - HELP message was displayed.
       ERRORLEVEL == 5 - Password or default switches
                         changed, message indicates success
                         or failure.

------------------------------------------------------------

SAFETY and SECURITY:

Most directory pruners either stop and demand confirmation
from the operator before deleting anything (some prompt for
everything) or are quick knock-offs that should never leave
the authors hands.  CHAINSAW is neither.  It is thoroughly
thought out and tested, and while it does not prompt for
confirmation, it does have password protection to prevent
unauthorized use and a rather elaborate set of switches to
either protect or unprotect such critical areas as the root
directory; read-only, hidden, and system files; and network
drives.  For those (such as the target user) who are
determined to make it easy for casual browsers to trash
their hard disks, the password feature can be turned off, if
you have the password.  NOTE: the default password is
"password" (lower case, no quote marks).  I buried that here
so that the potential user must at least scan the manual
before using the program.

       For those users who are concerned about viruses:
when released, the program was clean, and CIS has a very
good reputation for virus free software.  Nevertheless,
the best possible protection is to read, understand, and
recompile the source code.  It was written using Turbo C++
PRO (the PRO is important because the inline assembly
requires TASM and TASM2MSG, which are included in the
package) with the small memory model.  The only problems to
be expected with other C++ compilers would be with library
function names and the inline assembly code.  Most compilers
have equivalent functions and many have some way to deal
with inline assembly.  In case yours doesn't, you are on
your own.  Versions after Beta 5.2 were compiled with
Borland C++ for DOS.

12
.H:...CHAINSAW: more about
.H:
.H:

More about CHAINSAW:

Most of the code is pure C, but the real business of the
program, recursion through the directory tree, file
deletion, and directory removal uses a C++ class named
'dirkiller' which consists of a data block and a
constructor.  Construction of the object performs its work.
When the active instance of dirkiller encounters a
subdirectory, it creates a new instance of itself to process
it.  Each instance is destroyed (and removed from memory)
when it finishes.  This is not true recursion, it is in many
ways better.  The network drive test is implemented mostly
in assembly, and is built around DOS interrupt 0x21,
function 0x44, subfunction 0x09 which reports whether a
given drive is local or remote.  The source code is heavily
commented, except for the password changing and reading
functions.

       The program uses the small memory model, which
accounts for some of the apparently unneeded code that
processes the command tail arguments.  They seem to be
represented by far pointers and cannot be passed to
functions without a lot of trouble, or a different, and
slower, memory model.

       This program grew out of a co-worker's need for a
program to remove a bunch of subdirectories created by a
batch file.  It needed to work from the batch file without
operator intervention.  After a bit of research and a lot of
thinking about the problem, I decided to write a generalized
command line pruner for public distribution as freeware.
Obviously, that requires both more features and at least
some protection from accidental disk trashing.  It grew, and
grew, and grew.  There are several more features that I
would like to add, such as a switch to allow exclusion of
specified sub-branches of the target directory, and another
to exclude, as non-overrideable defaults, specified
directories and branches (such as C:\ and C:\DOS); but I had
to draw the line somewhere.  If there is a demand for them,
I will produce a version with those, and/or other, features.
If you want something really customized, I am willing to
talk money.

T.E.D.  1/11/92


13
                 Addenda 3/4/93 and 5/24/93

This program has been in almost daily use by a PC support
group (over 50 PCs) for over a year.  Most of the bugs
have been exterminated and usage patterns have formed and
have been analyzed. There has been only one change to the
dirkiller object in over six months, and it was rather minor
(to handle the special case of removing an already empty
directory (why anyone would use CHAINSAW instead of
RD for that completely escapes me)).

        The uses of the program fall into a few distinct
classes:
l---+---l-----+-L--2----T----3--T-+----4T---+---T5----+-T--R
        1)      A password protected copy in the network
                search path is used mostly to strip out old
                installations of user software before
                upgrade or reinstallation and to clean out
                user's c:\temp directories that get filled
                up with batch files left by DOSSHELL when
                the user reboots without dropping the
                program.  I took over a hundred out of one
                professor's \temp directory.  CHAINSAW is
                preferred because it cleans out the
                directory completely, including removal of
                subdirectories, which DEL *.*, with its
                annoying "Are you sure" prompt doesn't do.

        2)      Unprotected copies in the technicians'
                individual paths (ahead of the global copy)
                are used frequently for the original purpose
                of the program: to clean up after shuffling
                files through a \temp directory.

        3)      We use the same unprotected copies to delete
                dead directories and unwanted program
                installations, as after testing a new
                program.

        4)      An unprotected copy on the same floppy as a
                batch file is used to remove everything
                except authorized files from lab and student
                machines.  The batch file marks the allowed
                files as read-only and CHAINSAW is not
                allowed to delete them.  It also writes a
                report of what it removed and did not remove
                to STDOUT which is redirected to a data file
                on the floppy.  The DOS FIND service then
                separates the removals and non-removals into
                separate files for analysis.  The batch file
                also cleans up after itself by removing the
                read-only marks from those files that are
                not supposed to be read-only.
14

        5)      I use it to strip entire drives down to the
                volume label in preparation for installing a
                new version of DOS and a set of standard
                programs as part of a procedure for
                refurbishing old machines for new users.

        6)      We also carry it around to non-networked lab
                machines to clean up students working
                directories after they graduate (or
                otherwise leave).  A few of these machines
                are networked - and we use our own copies or
                the protected "public" copy instead of
                carrying a floppy around.

L---+----T----+----2----T----3--T-+----4T---+---T5----+-T--R

         The report generation code, on which I spent so
much time, is used only during the pre-semester cleanup
sweep.  The password feature is used only for the copy that
anyone can access over the network (of course, the other
copies are either kept filed away on floppies in drawers or
are protected by our network login passwords).

         I cannot say that the program is perfect or
bullet proof but, in over a year of use and testing, it has
never removed anything it wasn't told to remove.  There have
been malfunctions, but they have all been benign - they
have resulted in something not being removed or the program
refusing to do anything at all; these have all been fixed.
See CHAINSAW.CPP for the version history.

         One or two last notes: I thought it was
malfunctioning when it refused to remove c:\windows\fungame
from my own machine at home.  I had momentarily forgotten
that a SUBST was in effect for that directory (as drive F:).
DOS refused to let CHAINSAW remove what it thought of as a
root directory.  Even with the permission switch on, I got
the general ERROR message with the explanation that access
was denied.  I did once get a "Protected Mode Violation"
error from Windows 3.1 (in standard mode on a PS2-30/286),
but I get those all the time).  No, I will not explain why I
am trying to support Windows and Windows apps with a brain-
damaged computer.   The program has not been tested under
DOS 6.0; we were smart enough to pass on that one, so I
don't have access to it.

T.E.D.